<!--  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>IDL Definitions for the Stock Quoter Publisher/Subscriber Real-time CORBA Service</title>
</head>

<body
 text = "#000000"
 link = "#000fff"
 vLink= "#ff0f0f"
 aLink = "#0000ff"
 bgColor = "#ffffff">

<hr><h2>IDL Definitions for the Stock Quoter Publisher/Subscriber Real-time CORBA Service</h2><hr>

<P> Note: All the IDL definitions are included in the Stock module:
<PRE>
// IDL schema definition for the Stock Quoter Publisher/Subscriber Real-time CORBA Service.
module Stock
{
  ...
};
</PRE>

<h3>Common</h3>

This IDL file (Common.idl) contains all the exception(s), struct(s), value type(s) and
common interface(s) used by the Stock Quoter Publisher/Subscriber Real-time CORBA Service. The
generated lib of this idl file will be linked by all the other projects in the system. <P>

<li><h4>Defining the IDL exception</h4></li>

<PRE>
exception Invalid_Stock {};
</PRE>

This exception is used when the needed stock does not exist in the stock database. <P>

<li><h4>Defining the IDL struct</h4></li>

<PRE>
struct StockInfo
{
  string name;
  long high;
  long low;
  long last;
};
</PRE>

This struct contains the information about a stock. The items in this struct denote the
name, highest value, lowest value and last value of the stock respectively. <P>

<li><h4>Defining the IDL value types</h4></li>

Unlike CORBA Objects (which are passed by reference), instances of CORBA valuetype are
always passed by value. Like CORBA structs, they can contain state in the form of fields.
Unlike structs, however, they can have user-defined operations and support inheritance. <P>

<PRE>
valuetype StockName
{
  public string name;
};
</PRE>

This value type is used in the communication between stock distributor server and stock
broker client to handle the callback from distributor server whenever the value of a stock
the stock broker client interested in changes. <P>

<PRE>
valuetype Cookie
{
  public string cookie_id;
};
</PRE>

This value type is used to record the subscription relationship between stock distributor
server and stock broker client. It can also be used to unsubscribe the stock broker clien
from the stock distributor server. <P>

<li><h4>Defining the common IDL interfaces</h4></li>

<PRE>
interface Trigger
{
  void start ();
  void stop ();
}
</PRE>

This interface is inherited by the stock distributor interface because it need to be run as
a daemon that can be started and stopped by a system administrator. <P>

<PRE>
interface StockNameConsumer
{
  void push_StockName (in StockName the_stockname);
  
  attribute Cookie cookie;
};
</PRE>

This interface is used as a callback interface used by the distributor to notify brokers of updates. <P>

<PRE>
interface StockQuoter
{
  StockInfo get_stock_info (in string stock_name) raises Invalid_Stock;
};
</PRE>

This interface is used by brokers to get detailed stock information. <P>

<hr><h3>Distributor</h3>

This IDL file (Distributor.idl) contains IDL definitions for the Stock Distributor in the
Publish/Subscribe Real-time CORBA Stock Quoter Service. <P>

<li><h4>Defining the IDL exception</h4></li>

<PRE>
exception Invalid_Subscription {};
</PRE>

This exception is used when the needed cookie does not exist in the stock subscribers list. <P>

<li><h4>Defining the IDL interfaces</h4></li>

<PRE>
interface StockDistributor : Trigger
{
  /// Event source operation to establish connectivity.
  Cookie subscribe_notifier (in Stock::StockNameConsumer c, in RTCORBA::Priority priority);
  
  /// Event source operation to discontinue connectivity.
  Stock::StockNameConsumer unsubscribe_notifier (in Cookie ck)
    raises (Invalid_Subscription);;

  /// Factory operation to return StockQuoter object reference.
  StockQuoter provide_quoter_info ()
    raises (Invalid_Subscription);;
  
  /// Shutdown the object and terminate the application.
  oneway void shutdown ();
  
  /// Controls rate of updates.
  attribute long notification_rate;
};
</PRE>

This is the interface definition for Stock Distributor servers. <P>
The subscribe_notifier() and unsubscribe_notifier() operations are to subscribe/unsubscribe Stock Broker
clients with the Stock Distributor servers. <P>
The provide_quoter_info() factory operation returns StockQuoter object references that Stock Broker clients can
use to get more information about a particular stock. <P>
The shutdown() operation is a oneway operation which shuts down the object and terminates the application. <P>
The notification_rate attribute stands for the notification frequency that the Stock Distributor servers used 
to communicate with the Stock Broker clients. <P>

<PRE>
interface StockDistributorHome
{
  StockDistributor create ();
};
</PRE>

This is the interface definition for Stock Distributor Home.
This factory reduces the bookkeeping that CORBA applications must do to create and manage their objects. <P>

<hr><h3>Broker</h3>

This IDL file (Broker.idl) contains IDL definitions for the Stock Broker in the
Publish/Subscribe Real-time CORBA Stock Quoter Service. <P>

<li><h4>Defining the IDL interfaces</h4></li>

<PRE>
interface StockBroker
{
  /// Factory operation to return StockNameConsumer object reference.
  StockNameConsumer get_consumer_notifier ();

  /// Connects the broker to a supplied Quoter object reference.
  void connect_quoter_info  (in StockQuoter c);

  /// Disconnects a the quoter connection.
  StockQuoter disconnect_quoter_info ();

  /// Gets the current quoter connection.
  StockQuoter get_connection_quoter_info ();
  
  /// Shutdown the object and terminate the application.
  oneway void shutdown ();
};
</PRE>

This is the interface definition for Stock Broker clients. <P>
The get_consumer_notifier() operation returns an object reference of the StockNameConsumer interface
shown earlier. When the stock quoter system is initialized, this factory operation will be used to 
return the StockNameConsumer object that belongs to the StockBroker object. <P>
The connect_quoter_info() and disconnect_quoter_info() operations are used to connect/disconnect the StockBroker 
object with the StockQuoter object that's provided by the StockDistributor interface described next. <P>
The get_connection_quoter_info() operation is used to get the current connected StockQuoter object. <P>
The shutdown() operation is a oneway operation which shuts down the object and terminates the application. <P>

<PRE>
interface StockBrokerHome
{
  /// Create a StockBroker object.
  StockBroker create (in StockDistributor dist, in string stock_name);
};
</PRE>

This is the interface definition for Stock Broker Home.
This factory reduces the bookkeeping that CORBA applications must do to create and manage their objects. <P>

<hr><h3>Compiling the IDL files and generating the stub, skeleton and implementation files</h3>

To generate the helper files you need to invoke the IDL compiler, like this: <P>

<PRE>
tao_idl Common.idl
tao_idl -GI Broker.idl
tao_idl -GI Distributor.idl
</PRE>

The "-GI" flag is used to generate the frames for the implmentation files (*I.h and *I.cpp). You can
change the names of the files into *_i.h and *_i.cpp because the next time you run the IDL compiler,
these implemention files (*I.h and *I.cpp) will be overwritten by the newly generated implemention files
(with the same file names). <P>

However, you don't need to do this often, in fact you rarely have to do it at all because this can be handled
by <A HREF="mpc.html">writing and using a mpc file</A>. <P>

<hr><b>Email: </b><a href="mailto:"</a<ADDRESS>shanshan.jiang@vanderbilt.edu</ADDRESS>

</body>

</html>
